home *** CD-ROM | disk | FTP | other *** search
/ MacWorld: Complete Mac Interactive / Macworld Complete Mac Interactive CD)(1994).iso / The Best of BMUG / Utilities / Control Panels and Extensions / Zipple 1.9.1 / Zipple 1.9.1 Manual < prev    next >
Text File  |  1994-01-16  |  23KB  |  230 lines
  1. ========================
  2. Zipple 1.9.1 -- User Manual
  3. ========================
  4. Zipple is a control panel and extension for System 7 which allows you to replace the titles of your Apple, Balloon Help, Keyboard (if you have one), and Application menus with animated images, in color if you have a color screen. The displayed image can depend on the frontmost application or desk accessory, if you like. You can use the ready-made images that come with Zipple, or create your own with the sophisticated editor in the control panel.
  5.  
  6. Getting Started
  7. ==============
  8. It's easy. If this is the first version of Zipple you've installed, put the Zipple file in your Control Panels folder and the "Zipple Preferences" file in your Preferences folder. Now, restart your Macintosh. You should see Zipple's icon drawn at the bottom of your screen, and when you get to the Finder, your Apple menu should be replaced by a spinning earth, the question mark in your Balloon Help menu title should be spinning around, and there should be fireworks in the screen of the Mac on top of your Application menu. If the startup icon had a big X through it, you won't see all this spiffy stuff. Consult the Troubleshooting section at the end of this manual to see if I have anticipated your problem and can offer a solution.
  9.  
  10. Upgrading
  11. =========
  12. If you already have a version of Zipple older than 1.9 installed (i.e. one that doesn't use a "Zipple Preferences" file), remove it from your Control Panels folder (don't throw it away yet!), and put the new one in there. Then, open the new control panel. An alert should pop up indicating that Zipple couldn't find its preferences. You can choose to create an empty preferences file, or to extract your preferences from your older version. If you opt to extract your old preferences, a standard dialog box will pop up in which you can select your old Zipple file. All preferences and Zipples are copied over from version 1.8. From 1.7 and 1.7.1, the Zipples are copied over and a "default" set of preferences is created. Zipples aren't copied over from versions earlier than 1.7; use the Import/Export option to get them. The default preference set is also created for versions earlier than 1.7. Restart to activate the new version.
  13.  
  14. Preferences
  15. ===========
  16. All of Zipple's settings are stored in the "Zipple Preferences" file in your Preferences folder (inside your System Folder). In addition, all of your Zipples are stored there too, so don't trash your preferences file expecting to lose only your settings, as you will be angry with the actual result!
  17.  
  18. The Control Panel
  19. ================
  20. Go into your Control Panels folder and open up the Zipple control panel. A big fat window with lots of confusing stuff should appear on your screen. Don't be overwhelmed, I'll explain everything (except for how something this simple could get this complicated... for that I offer two words: "creeping featuritis"). Here's a detailed explanation of each item in the control panel window, starting at the upper left and working our way generally down and to the right.
  21.  
  22. Zipple logo/author credit
  23. -----------------------
  24. Neat, isn't it? (Hey Lloyd, command-click this!)
  25.  
  26. On checkbox
  27. -----------
  28. This controls whether Zipple zipples or not.
  29.  
  30. Icon checkbox
  31. -------------
  32. This button controls whether or not Zipple's icon gets plotted at the bottom of your screen when you start up. If errors occur when Zipple is loading, it will always plot the X-ed out icon, regardless of the setting of this control.
  33.  
  34. Zipple list
  35. ----------
  36. This list shows all the Zipples that have been created so far. You can scroll up and down to see all of them. The currently selected Zipple will animate, so you can preview what it will look like in your menu bar.
  37.  
  38. Popup menu
  39. -----------
  40. This menu allows you to choose which menu or application you are changing the settings for. The settings for a particular menu or application are governed by the four radio buttons below this popup, and the Zipple list. If you choose a menu title (the first four items), the settings will always apply for that menu. If you choose an application or DA (the rest of the menu) the settings will only apply when that application or DA is frontmost, and you have selected "Front App" for one of your menus. To choose an additional application or desk accessory for which you'd like to have a Zipple, simply choose the "Add New App or DA..." item. A standard dialog box will pop up so you can choose an application or DA. When you do so, its name will appear in the menu, and you can choose a Zipple for it. If you want to delete an application from the menu, just hold down the Command key when you click in the menu, select the offending application or DA, and release. Its menu item will disappear without a trace.
  41.  
  42. Selection/Random/Front App/None radio buttons
  43. --------------------------------------------
  44. These four radio buttons and the Zipple list determine what Zipple is displayed over what menu title, or for which application. If you choose "Selection", you must also select a Zipple in the Zipple list. That Zipple will always be used to replace the menu title, or will always appear when that application becomes frontmost. If you choose "Random", a random Zipple will be chosen to replace the menu title at every startup. If you choose "Front App", the image displayed over the menu title will change depending on what application or DA is frontmost. If you haven't chosen a Zipple for the application that is in front, no animation will take place until you switch to an application for which you -have- chosen a Zipple. If you choose "None", no Zipple will replace the menu title, i.e. you will see the regular title. You can choose "None" for an application, but it would make more sense to just delete that application from the menu, as described before. Note that a "Front App" selection will not take effect until you close the control panel. All other choices take effect as soon as you hit "Set".
  45.  
  46. Set button
  47. ----------
  48. Use this button to lock in and save your settings for the current menu title, application or DA. Your changes are not saved until you hit this button, which allows you to fiddle around without affecting your saved settings.
  49.  
  50. Speed scroll bar
  51. ---------------
  52. This determines how fast the Zipple over the currently selected menu is animated. Move it all the way to the right to have it go as quickly as it can go. Move it all the way to the left to chill out and slow down.
  53.  
  54. New… button
  55. ------------
  56. So, you wanna make a new Zipple, eh? Well, this button is the key to paradise. Just click it, type in a name for the Zipple in the dialog box that pops up, click OK, and you're all set.
  57.  
  58. Delete button
  59. -------------
  60. Just as yin has yang, so too does New… have Delete. Use this button to eradicate an offensive Zipple from the face of the cosmos. Careful! This isn't Undo-able.
  61.  
  62. Name… button
  63. -------------
  64. Click this button to change the name of the currently selected Zipple.
  65.  
  66. Import/Export button
  67. --------------------
  68. You've just created a Mona Lisa Zipple with waggling eyebrows and smirking lips. You wanna show it to someone else, but you don't wanna lug the whole Zipple prefs file around. Or, your buddy hands you a disk saying "Check out this cool Zipple!". What do you do? The answer: Import/Export. Clicking this button brings up a dialog box with two scrolling lists and a couple of buttons. The list on the left is a list of the Zipples currently available to the Zipple control panel. The list on the right is empty at first, but that will change as you get further into this. You can create a new file to export Zipples to (the New… button), or open up an existing file to import from or export to (the Open… button). These two buttons bring up the standard Macintosh file dialogs we all know and love, so I'll assume you know how to use them. Now you've got a file open. Its name appears over the right list, and if it had any Zipples in it, they appear in the list below the name. Click on a Zipple in the left list. Notice how the Export button lights up, indicating that you can now export. Click on a Zipple in the right list. The Export button changes to an Import button. Coolness. When you're all done here, click the Done button to get back to the main window.
  69. NOTE: if you created your own Zipples with an earlier version of Zipple, you must use the Import option to bring them into this version, since versions 1.8 and later use a different format for storing Zipples. If you just copy the resources over with ResEdit or something, they won't work.
  70.  
  71. Frame editing box, toolboxes, pattern and color popups
  72. -------------------------------------------------
  73. This is where you can get down to the serious business of editing the frames of your Zipple. Just to the left of the frame editing window are two toolboxes that offer some neat features. The top toolbox allows you to choose between editing in pencil (pixel at a time) mode, and paint-bucket (lots of pixels at a time) mode. When the cursor passes over the editing box, it'll change into a pencil or a paint-bucket to remind you which mode you're in. On black and white screens, the pencil always draws and erases black pixels. In color mode, it's more like a crayon. You can choose a color for it from the popup at the far right of the control panel, and then draw and erase pixels in that color. The 15th color is different, which is why it looks different (it's the one with the little box in it instead of a color). Pixels filled with this "color" will appear in the editing box with small dots in the middle of them. They will turn the same color as the menu bar background when the Zipple is drawn in the menu bar. In black and white, use the left-hand popup, which contains 16 black and white patterns (the background color business doesn't apply). The paint bucket spills out the pattern selected in the popup (in black and white), in the selected color (on color screens).
  74.  
  75. The bottom toolbox allows you to perform some pretty nifty operations on the current frame. The first two icons allow you to rotate the frame in 90 degree increments. The middle four allow you to nudge the entire frame one pixel in the indicated directions. The last two allow you to flip the frame vertically or horizontally.
  76.  
  77. You can use the standard edit menu cut, copy, paste, and clear functions.
  78.  
  79. Use the scroll bar at the bottom of the editing box to scroll through the frames of the Zipple.
  80.  
  81. You can undo changes made to a frame, but once you scroll to a different frame, or select a different Zipple, your changes to the frame become permanent.
  82.  
  83. Grabber button
  84. --------------
  85. All right. You're no artist. You can't even draw flies. Have no fear. You can grab those nifty pictures that professional graphic artists get paid to draw, touch them up a bit, and make them into the coolest Zipple ever. All you need is the handy-dandy grabber, which you can access by hitting this button. Again a dialog box comes up with two scrolling lists. The left list contains the frames of the current Zipple. The right hand list is initially empty. Just like in the Import/Export dialog box, use the Open… button to open up a file to grab pictures out of. The right list will fill up with the resources that the file you opened contains. Currently, Zipple looks for CURS (cursor), SICN (small icon), ics# (black and white small icon), kcs# (small keyboard icon), kcs4 (color small keyboard icon), and ics4 (color small icon) resources. You can also grab the frames of another Zipple by opening up your prefs file. To grab a picture, simply click on it in the right list, hold down the mouse button, and drag it to the appropriate frame in the left list. The frame will light up when you are in the right place. Let go of the mouse button, and the picture is copied over. When you are done, you can hit the OK button to save your changes to the frames, or hit the Cancel button to undo any changes you have made to the frames, thus restoring the Zipple to its state before you opened up the Grabber. (A good way to make a Zipple for an application is to grab some icons out of it, then animate them.)
  86.  
  87. Edit Color checkbox
  88. ------------------
  89. Click here to edit the frames of the Zipple in color. Each Zipple has a color and a black and white version. If you're always running in color, you can ignore the black and white version.
  90.  
  91. Insert Frame / Delete Frame
  92. --------------------------
  93. These buttons insert and delete frames from the current Zipple. An inserted frame will look just like the frame before it. If you try to delete a frame from a Zipple with only one frame, Zipple will ask if you want to delete the whole thing.
  94.  
  95. System Requirements
  96. ====================
  97. Zipple will work on any Macintosh running System 7 or later, and works just as well in color as in black and white. Zipple uses about 5k of memory on black and white machines, and about 10k on color machines. Of course, if you create massively long Zipples, these requirements will increase somewhat.
  98.  
  99. Troubleshooting
  100. ===============
  101. Zipple is a very stable piece of software. I've heard very few reports of it causing trouble. I've fixed (or attempted to fix) all known bugs and glitches as they have been reported to me, so if something does go wrong, drop me a line and I'll see what I can do.
  102.  
  103. If you get the X-ed out icon at startup, this indicates that Zipple could not load itself into memory properly. This happens if you have a System earlier than System 7. Solution: get System 7. It's been out for three years, it's stable, and hey, I run it on my wimpy little Macintosh SE and it runs just fine. Besides, System 6 is not nearly as cool. So there. Nyah.
  104. It can also happen if you don't have enough memory. I can't say much here except: get more. Zipple doesn't require that much memory at all, so if it is having memory problems, you will be too.
  105. This can also happen if you have no preferences file. Open the control panel, and an alert will appear allowing you to create a preferences file.
  106.  
  107. Now, you may be expecting a long list of other weird crashes and incompatibilities, but I'm sad to say I've only heard of a few. I had two reports of Zipple crashing when the Import/Export and Grabber dialog boxes were brought up. This is fixed in version 1.8. There have been two reports of Zipple 1.8 crashing when opening or closing the control panel, but I haven't been able to reproduce this behavior. There were also two reports of 1.8 crashing when various utilities were used to change the screen depth. This is fixed in version 1.9.
  108.  
  109. Holy mackerel! This thing is incredible! How much?
  110. ==============================================
  111. Zipple is shareware. If you feel like sending $10, by all means do so. If you feel like sending a nice letter or postcard, do that. If you want to send a cool shareware product of your own, please do! If you don't feel like sending anything, don't send anything. There are no annoying registration dialog boxes full of accusatory language getting in your face, no hidden time-bombs that cause the program to stop working in a month, no bugs that are only fixed in a version available to people who pay, nothing like that. A program with that stuff in it isn't shareware, it's a demo. Shareware is complete, working software that you can try before you buy. If you use a piece of shareware, you should pay for it. However, my attitude about payment is a little more laid back than most. After five years as a student, I realize that money is tight, people are forgetful, etc. etc., so I don't get worked up about it. But remember, shareware is a valuable institution, so do your best to keep it alive.
  112.  
  113. Send your checks (US$ drawn on a US bank), postal money orders, postcards, letters, disks, etc., to:
  114. Christopher Suley
  115. 4310 Albany Drive Apt K207
  116. San Jose, CA 95129-1244
  117.  
  118. Internet email:    csuley@netcom.com
  119. America Online:    ChrisSuley
  120.  
  121. I'm kind of a techie. Tell me some juicy details.
  122. ===========================================
  123. Okay. The driver (DRVR) gets time from the System periodically and uses CopyBits to draw the Zipples over the menu bar. This is not interrupt time, so I don't have to worry about moving memory. This is SystemTask time, which is usually called by WaitNextEvent. The frames of a Zipple are stored in ZCN# and ZCN4 resources. Each resource starts with a 4 byte value which is the count of the frames in the Zipple, followed by the frame data. In the ZCN# resources, this is just a series of 32 byte bitmaps. In the ZCN4 resources, this is a series of 4 bit deep pixmaps (128 bytes). The colors come from the standard 4 bit deep color table, minus the one color that is changed to be the same as the menu bar background. To get the application specific Zipples, I keep Zipple's preference file open, behind the System file in the resource file chain. I keep track of the front process with GetFrontProcess. If it changes, I look up the creator of the new front process in a list, then choose the corresponding Zipple. Zipple is compiled with Symantec's awesome cool THINK C 6.0.1. It uses multi-segment code resources and the THINK driver glue, so I guess portions of it are ©'ed by Symantec.
  124.  
  125. Acknowledgements
  126. =================
  127. I was inspired to write Zipple by the Earth extension written by Stefan Bilaniuk. In fact, I snagged the Earth and Earth II images from versions 1.0 and 1.1 of Earth. Bob Andris sent me the color Spinning Apple, 3-D Spin Apple, and Finder Zipples. Lloyd Wood made many helpful suggestions, most of which were incorporated into version 1.2. Scott Gruby reported a serious bug in version 1.3, allowing me to quickly squash it. Mark Manning gave me a very detailed and helpful description of a bug in version 1.3.1. Mason Bliss (author of the fine freeware screen saver Basic Black) prodded me into actually getting version 1.7 done. Mason Bliss, Bob Andris, and Carl Constantine reported bugs in 1.7 that I eradicated in 1.7.1. Jim Pailin helped me finally fix the bug in Import/Export and the Grabber. Bob Andris pointed out that I could handle DAs as well as applications. Eric Piotrowski suggested the renaming and flipping functions added in 1.9.
  128.  
  129. Version history
  130. ==============
  131. 1.9.1
  132. *    Another dratted bug fix!  Two bonehead mistakes are fixed.
  133. *    No longer crashes with a type 1 (bus) error when launching a program with no menus, such as a self-extracting archive.  It's a mystery to me why this doesn't happen on my machine, as the processor in an SE is more easily bus-errored than any other.  Oh well.
  134. *    No longer allows the speed scroll bar in the control panel to become active and cause things to go wacko when it is supposed to be inactive.
  135.  
  136. 1.9
  137. *    Now uses a preferences file, so you can more easily maintain your settings and Zipples as future upgrades come out.
  138. *    Can now choose Zipples for desk accessories as well as applications.
  139. *    Can now rename previously created Zipples.
  140. *    Flip horizontal and flip vertical tools added to frame editor.
  141. *    The color paint bucket now uses the currently selected pattern in the currently selected color.
  142. *    Color and pattern are now handled by popup menus, rather than a static palette.
  143. *    Now automatically detects where your menus are, rather than requiring you to tell it in a dialog box.
  144. *    In addition, Zipple now detects when the menus it's meant to be replacing are actually on the screen, and only draws when they are present.
  145. *    No longer crashes when you change the depth of your screen. This seems to have only affected machines running in 32 bit mode. (Thanks go to the users who reported this, to MacsBug, to Tech Note 155, and to my parents for upgrading their LC to 10 megs of memory, thus requiring 32 bit mode).
  146. *    The grabber can now grab all of the icons contained in a SICN resource, not just the first one. The grabber can also grab frames from Zipples.
  147. *    Some bugs in the control panel were fixed. Mostly these involved the wrong radio button being selected sometimes.
  148. *    My new snail mail address is included in this file.
  149.  
  150. 1.8
  151. *    Addition of "Front App" mode.
  152. *    Eliminated masks again.
  153. *    You can change the speed of Zipple's animation for each menu.
  154. *    Zipple no longer draws over iconic menus added by other programs.
  155. *    The Zipple list draws faster, and handles long names more elegantly.
  156. *    The Grabber can now grab kcs# and kcs4 resources.
  157. *    No crashes when the Import/Export or Grabber windows are brought up.
  158. *    Now using the Gestalt 'SAVR' selector -properly-!  This should alleviate the problem of Zipple "disappearing" when a screen saver kicks in.
  159.  
  160. 1.7.1
  161. *    No longer crashes when "Set" is hit on a black and white machine.
  162. *    No longer displays strange colors behind the Zipple on a color screen.
  163. *    Can choose a Zipple for the Keyboard menu.
  164. *    Detecting screen savers with the Gestalt 'SAVR' selector.
  165.  
  166. 1.7
  167. *    Major upgrade. Now requires System 7.
  168. *    Allows Zipples to appear over the Apple, Balloon Help, and/or Application menu simultaneously.
  169. *    Added masks.
  170. *    Requires less memory than before on black and white machines.
  171. *    Added clockwise frame rotation button. -duh-
  172. *    The cursor changes shape in the editing box.
  173. *    Using some of Pete Resnick's driver 2.1.8 code to install the driver.
  174.  
  175. 1.6.1
  176. *    Bug fix release.
  177. *    No more crashes while nudging or rotating frames in the color editor.
  178. *    Fixed the very last bug in the operation of the speed control.
  179.  
  180. 1.6
  181. *    Added toolboxes.
  182. *    Added the ability to Undo changes made to frames while editing.
  183. *    Put patterns in the black and white palette.
  184. *    Fixed a cosmetic flaw in the list of Zipples in the control panel.
  185. *    Clicks in the editing box with no Zipple selected no longer crash.
  186.  
  187. 1.5
  188. *    Balloon Help added.
  189. *    Added a paint bucket feature to the color editor.
  190. *    Fixed a couple of bugs that caused memory leaks when editing.
  191. *    Fewer "Out of Memory" errors under System 6 and MultiFinder.
  192. *    Fixed a bug that prevented Zipple from working on a Macintosh Plus.
  193. *    The 'Clear' command now updates the frame editing box properly.
  194. *    Fixed a bug in the operation of the speed control.
  195. *    Tightened up the code a bit, making it a little smaller.
  196. *    Using Patrick Beard's "ShowIconFamily" code to draw the startup icon.
  197.  
  198. 1.4
  199. *    Added the "Grabber".
  200. *    Changed the interface of the Import/Export feature somewhat.
  201. *    The Cut command can now be used, in addition to Copy, Paste, and Clear.
  202. *    Editing commands now use the standard Clipboard.
  203. *    Fixed a cosmetic flaw that arose when Zipple was used with Rival.
  204.  
  205. 1.3.1
  206. *    Bug fix. Version 1.3 would crash machines at startup.
  207.  
  208. 1.3
  209. *    Zipple now REALLY always uses the color images when it should.
  210. *    You can now choose to have a random Zipple picked at startup.
  211. *    Zipple can now draw over the Apple, Balloon Help, or Application menus.
  212.  
  213. 1.2
  214. *    Zipple now always uses the color images when it should.
  215. *    Double-clicking on a Zipple in the list chooses it as your current Zipple.
  216. *    The speed control now works more sensibly.
  217. *    If an error occurs, the X-ed out startup icon ALWAYS appears.
  218.  
  219. 1.1
  220. *    Import and Export of Zipples.
  221. *    Support for copy, paste, and clear operations on frames.
  222. *    No more white artifacts on the screen when your menu bar is not white.
  223. *    Masks are no longer necessary.
  224. *    The edit box is always redrawn properly.
  225.  
  226. 1.0
  227. *    First release
  228.  
  229. Christopher Suley
  230. January 16, 1994